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ABOUT THIS CHAPTER 


The System Error Handler is the part of the Operating System that assumes 
control when a fatal system error occurs. This chapter introduces you to the 
System Error Handler and describes how your application can recover from system 
errors. 


You'll already need to be somewhat familiar with most of the User Interface 
Toolbox and the rest of the Operating System. 
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ABOUT THE SYSTEM ERROR HANDLER 


The System Error Handler assumes control when a fatal system error occurs. Its 
main function is to display an alert box with an error message (called a system 
error alert) and provide a mechanism for the application to resume execution. 


Note: The system error alerts simply identify the type of problem encountered 
and, in some cases, the part of the Toolbox or Operating System 
involved. They don't, however, tell you where in your application code 
the failure occurred. 


Because a system error usually indicates that a very low-level part of the 
system has failed, the System Error Handler performs its duties by using as 
little of the system as possible. It requires only the following: 


¢ The trap dispatcher is operative. 

e The Font Manager procedure InitFonts has been called (it's called when 
the system starts up). 

« Register A7 points to a reasonable place in memory (for example, not to 
the main screen buffer). 

¢ A few important system data structures aren't too badly damaged. 


The System Error Handler doesn't require the Memory Manager to be operative. 


The content of the alert box displayed is determined by a system error alert 
table, a resource stored in the system resource file. There are two different 
system error alert tables: a system startup alert table used when the system 
starts up, and a user alert table for informing the user of system errors. 


The system startup alerts are used to display messages at system startup such as 
the "Welcome to Macintosh" message (Figure 1). They're displayed by the System 
Error Handler instead of the Dialog Manager because the System Error Handler 
needs very little of the system to operate. 


The user alerts (Figure 2) notify the user of system errors. The bottom right 
corner of a user alert contains a system error ID that identifies the error. 
Usually the message "Sorry, a system error occurred", a Restart button, and a 
Resume button are also shown. If the Finder can't be found on a disk, the 
message "Can't load the finder" and a Restart button will be shown. The 
Macintosh will attempt to restart if the user clicks the Restart button, and the 
application will attempt to resume execution if the user clicks the Resume 
button. 
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Welcome to Macintosh. 


Figure 1-3 ystem Startup Alert 
Figure 1-System Startup Alert 


iN 
é Sorry, a system error occurred. 


Restart HE SUFFEG 


Figure §6-Strings Drawn in Routines 
Figure 2—User Alert 


The "Please insert the disk:" message displayed by the File Manager is also a 
user alert; however, unlike the other alerts, it's displayed in a dialog box. 


The summary at the end of this chapter lists the system error IDs for the 
various user alerts, as well as the system startup alert messages. 


A new system error, user alert ID 84, has been added. This error results when 
the Menu Manager tries to access a menu that's been purged. 
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RECOVERING FROM SYSTEM ERRORS 


An application recovers from a system error by means of a resume procedure. You 
pass a pointer to your resume procedure when you call the Dialog Manager 
procedure InitDialogs. When the user clicks the Resume button in a system error 
alert, the System Error Handler attempts to restore the state of the system and 
then calls your resume procedure. 


Assembly-language note: The System Error Handler actually restores the value 
of register A5 to what it was before the system error 
occurred, sets the stack pointer to the address stored 
in the global variable CurStackBase (throwing away the 
stack), and then jumps to your resume procedure. 


If you don't have a resume procedure, you'll pass NIL to InitDialogs (and the 
Resume button in the system error alert will be dimmed). 
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SYSTEM ERROR ALERT TABLES 


This section describes the data structures that define the alert boxes displayed 
by the System Error Handler; this information is provided mainly to allow you to 
edit and translate the messages displayed in the alerts. Rearranging the alert 
tables or creating new ones is discouraged because the Operating System depends 
on having the alert information stored in a very specific and constant way. 


In the system resource file, the system error alerts have the following resource 
types and IDs: 


Table Resource type Resource ID 
System startup alert table 'DSAT' 0 
User alert table ‘INIT' 2 


Assembly-language note: The global variable DSAlertTab contains a pointer to 
the current system error alert table. DSAlertTab 
points to the system startup alert table when the 
system is starting up; then it's changed to point to 
the user alert table. 


A system error alert table consists of a word indicating the number of entries 
in the table, followed by alert, text, icon, button, and procedure definitions, 
all of which are explained below. The first definition in a system error alert 
table is an alert definition that applies to all system errors that don't have 
their own alert definition. The rest of the definitions within the alert table 
needn't be in any particular order, nor do the definitions of one type need to 
be grouped together. The first two words in every definition are used for the 
same purpose: The first word contains an ID number identifying the definition, 
and the second specifies the length of the rest of the definition in bytes. 


An alert definition specifies the IDs of the text, icon, button, and procedure 
definitions that together determine the appearance and operation of the alert 
box that will be drawn (Figure 3). The ID of an alert definition is the system 
error ID that the alert pertains to. The System Error Handler uses the system 
error ID to locate the alert definition. The alert definition specifies the IDs 
of the other definitions needed to create the alert; 0 is specified if the alert 
doesn't include any items of that type. 


A text definition specifies the text that will be drawn in the system error 
alert (Figure 4). Each alert definition refers to two text definitions; the 
secondary text definition allows a second line of text to be added to the alert 
message. (No more than two lines of text may be displayed.) The pen location at 
which QuickDraw will begin drawing the text is given as a point in global 
coordinates. The actual characters that comprise the text are suffixed by one 
NUL character (ASCII code 0). 


Warning: The slash character (/) can't be used in the text. 
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Procedure definition ID brord] 


Button definition ID byrord) 


Figure 3-Alert Definition 
Figure 3—-Alert Definition 


Figure 4-Tert Definition 
Figure 4—Text Definition 


An icon definition specifies the icon that will be drawn in the system error 
alert (Figure 5). The location of the icon is given as a rectangle in global 
coordinates. The 128 bytes that comprise the icon complete the definition. 


Langth of rest of definition byrord) 


Figure 5—-Icon Definition 
Figure 5—Icon Definition 


A procedure definition specifies a procedure that will be executed whenever the 
system error alert is drawn (Figure 6). Procedure definitions are also used to 
specify the action to be taken when a particular button is pressed, as described 
below. Most of a procedure definition is simply the code comprising the 
procedure. 
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Procedure definition ID bord] 
Langth of rast of definition bord) 


Figure 6—Procedure Definition 
Figure 6—Procedure Definition 


A button definition specifies the button(s) that will be drawn in the system 
error alert (Figure 7). It indicates the number of buttons that will be drawn, 
followed by that many six-word groups, each specifying the text, location, and 
operation of a button. 


Shiner ID brand 
Button loestion Factangla) 
Frocedire definition ID brord] 


Figure 7—Button Definition 
Figure 7—Button Definition 


The first word of each six-word group contains a string ID (explained below) 
specifying the text that will be drawn inside the button. The button's location 
is given as a rectangle in global coordinates. The last word contains a 
procedure definition ID identifying the code to be executed when the button is 
clicked. 


The text that will be drawn inside each button is specified by the data 
structure shown in Figure 8. The first word contains a string ID identifying the 
string and the second indicates the length of the string in bytes. The actual 
characters of the string follow. 


Each alert has two button definitions; these definitions have sequential button 
definition IDs (such as 60 and 61). The button definition ID of the first 
definition is placed in the alert definition. This definition is used if no 
resume procedure has been specified (with a call to the Dialog Manager's 
InitDialogs procedure). If a resume procedure has been specified, the System 
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Error Handler adds 1 to the button definition ID specified in the alert 
definition and so uses the second 


Length of sting baron) 


Taxt (ASCII charac ars) 


Figure 6-Stings Drawn in Buttons 
Figure 8-Strings Drawn in Buttons 
button definition. In this definition, the procedure for the Resume button 


attempts to restore the state of the system and calls the resume procedure that 
was specified with InitDialogs. 
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SYSTEM ERROR HANDLER ROUTINE 


The System Error Handler has only one routine, SysError, described below. Most 
application programs won't have any reason to call it. The system itself calls 
SysError whenever a system error occurs, and most applications need only be 
concerned with recovering from the error and resuming execution. 


PROCEDURE SysError (errorCode: INTEGER); 


Trap macro —_SysError 
On entry DO: errorCode (word) 
On exit All registers changed 


SysError generates a system error with the ID specified by the errorCode 
parameter. 


It takes the following precise steps: 


1. It saves all registers and the stack pointer. 

2. It stores the system error ID in a global variable (named DSErrCode). 

3. It checks to see whether there's a system error alert table in memory 
(by testing whether the global variable DSAlertTab is 0); if there 
isn't, it draws the "sad Macintosh" icon. 

4. It allocates memory for QuickDraw globals on the stack, initializes 
QuickDraw, and initializes a grafPort in which the alert box will be 
drawn. 

5. It checks the system error ID. If the system error ID is negative, the 
alert box isn't redrawn (this is used for system startup alerts, which 
can display a sequence of consecutive messages in the same box). If the 
system error ID doesn't correspond to an entry in the system error alert 
table, the default alert definition at the start of the table will be 
used, displaying the message "Sorry, a system error occurred". 

6. It draws an alert box (in the rectangle specified by the global variable 
DSAlertRect). 

7. If the text definition IDs in the alert definition for this alert aren't 
0, it draws both strings. 

8. If the icon definition ID in the alert definition isn't 0, it draws the 
icon. 

9. If the procedure definition ID in the alert definition isn't 0, it 
invokes the procedure with the specified ID. 

10. If the button definition ID in the alert definition is 0, it returns 
control to the procedure that called it (this is used during the disk- 
switch alert to return control to the File Manager after the "Please 
insert the disk:" message has been displayed). 

11. If there's a resume procedure, it increments the button definition ID 
by 1. 

12. It draws the buttons. 

13. It hit-tests the buttons and calls the corresponding procedure code 
when a button is pressed. If there's no procedure code, it returns to 
the procedure that called it. 
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SUMMARY OF THE SYSTEM ERROR HANDLER 


Routines 


PROCEDURE SysError (errorCode: INTEGER); 


User Alerts 


ID 


1 
2 
3 


17-24 


Explanation 


Bus error: Invalid memory reference; happens only on a Macintosh XL 
Address error: Word or long-word reference made to an odd address 
Illegal instruction: The MC68000 received an instruction it didn't 
recognize. 

Zero divide: Signed Divide (DIVS) or Unsigned Divide (DIVU) 
instruction with a divisor of 0 was executed. 

Check exception: Check Register Against Bounds (CHK) instruction was 
executed and failed. Pascal "value out of range" errors are usually 
reported in this way. 

TrapV exception: Trap On Overflow (TRAPV) instruction was executed 
and failed. 

Privilege violation: Macintosh always runs in supervisor mode; 
perhaps an erroneous Return From Execution (RTE) instruction was 
executed. 

Trace exception: The trace bit in the status register is set. 

Line 1010 exception: The 1010 trap dispatcher has failed. 

Line 1111 exception: Unimplemented instruction 

Miscellaneous exception: All other MC68000 exceptions 

Unimplemented core routine: An unimplemented trap number was 
encountered. 

Spurious interrupt: The interrupt vector table entry for a 
particular level of interrupt is NIL; usually occurs with level 4, 
5, 6, or 7 interrupts. 

I/0 system error: The File Manager is attempting to dequeue an 
entry from an I/0 request queue that has a bad queue type field; 
perhaps the queue entry is unlocked. Or, the dCtlQHead field was 

NIL during a Fetch or Stash call. Or, a needed device control entry 
has been purged. 

Segment Loader error: A GetResource call to read a segment into 
memory failed. 

Floating point error: The halt bit in the floating-point environment 
word was set. 

Can't load package: A GetResource call to read a package into 
memory failed. 

Can't allocate requested memory block in the heap 

Segment Loader error: A GetResource call to read 'CODE' resource 

0 into memory failed; usually indicates a nonexecutable file. 

File map destroyed: A logical block number was found that's greater 
than the number of the last logical block on the volume or less than 
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the logical block number of the first allocation block on the volume. 


28 Stack overflow error: The stack has expanded into the heap. 
30 "Please insert the disk:" File Manager alert 
31 Not the requested disk 
33 Negative ZcbFree value 
41 The file named "Finder" can't be found on the disk. 
84 A menu has been purged 
100 Can't mount system startup volume. The system couldn't read the 
system resource file into memory. 
32767 "Sorry, a system error occurred": Default alert message 


System Startup Alerts 


"Welcome to Macintosh" 

"Disassembler installed" 

"MacsBug installed" 

"Warning—this startup disk is not usable" 


Assembly-Language Information 
Constants 


; System error IDs 


dsBusError . EQU 1 ;bus error 

dsAddressErr .EQU 2 ;address error 
dsItlInstErr .EQU 3 ;illegal instruction 
dsZeroDivErr .EQU 4 ;zero divide 

dsChkErr .EQU 5 ;check exception 
dsOvflowErr .EQU 6 ;trapV exception 
dsPrivErr .EQU 7 ;privilege violation 
dsTraceErr . EQU 8 ;trace exception 
dsLineAErr .EQU 9 ; line 1010 exception 
dsLineFErr .EQU 10 ; line 1111 exception 
dsMiscErr . EQU 11 ;miscellaneous exception 
dsCoreErr .EQU 12 ;unimplemented core routine 
dsIrgErr . EQU 13 ;Spurious interrupt 
dsIOCoreErr .EQU 14 ;1/0 system error 
dsLoadErr .EQU 15 ;Segment Loader error 
dsFPErr . EQU 16 ;floating point error 
dsNoPackErr .EQU 17 ;can't load package 0 
dsNoPk1 . EQU 18 ;can't load package 1 
dsNoPk2 . EQU 19 ;can't load package 2 
dsNoPk3 .EQU 20 ;can't load package 3 
dsNoPk4 .EQU 21 ;can't load package 4 
dsNoPk5 .EQU 22 ;can't load package 5 
dsNoPk6 .EQU 23 ;can't load package 6 
dsNoPk7 . EQU 24 ;can't load package 7 
dsMemFullErr .EQU 25 ;can't allocate requested block 
dsBadLaunch .EQU 26 ;Segment Loader error 
dsFSErr .EQU 27 ;file map destroyed 
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dsStkNHeap .EQU 28 ;stack overflow error 


dsReinsert . EQU 30 ;"Please insert the disk:" 
dsNotThel EQU 31 ;not the requested disk 
negZcbFreeErr EQU 33 ;ZcbFree is negative 

menuPrgErr EQU 84 ;happens when a menu is purged 
dsSysErr . EQU 32767 ;undifferentiated system error 
Routines 

Trap macro On entry On exit 

_SysError DO: errorCode (word) All registers changed 
Variables 

DSErrCode Current system error ID (word) 

DSAlertTab Pointer to system error alert table in use 
DSAlertRect Rectangle enclosing system error alert (8 bytes) 


END OF DOCUMENT 
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